home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / src / Tools / man2html-2.0.2 / doc / man2html.txt < prev   
Text File  |  1995-06-18  |  15KB  |  407 lines
  1.  
  2.                                        
  3.    __________________________________________________________________________
  4.                                        
  5.                                    MAN2HTML
  6.                                        
  7.    A Perl program to convert Unix manpages to HTML.
  8.    
  9.    
  10.      _________________________________________________________________
  11.    
  12. Description
  13.  
  14.    man2html takes formatted nroff in standard input (STDIN) and outputs
  15.    the HTML to standard output (STDOUT). The formatted nroff output is
  16.    surrounded with <PRE> tags with the following exceptions/additions:
  17.    
  18.      * Section heads are wrapped in HTML header tags. See Section Head
  19.        Map File for more information. This feature can be turned off
  20.        with the -noheads command-line option.
  21.        
  22.      * Overstriken words designated with the "<char><backspace><char>"
  23.        sequences are wrapped in <STRONG> tags.
  24.        
  25.      * Overstriken words designated with the "_<backspace><char>"
  26.        sequences (ie. underlined words) are wrapped in <EM> tags.
  27.        
  28.    man2html also does the following:
  29.    
  30.      * Merges the multi-page formatted nroff into a single page. See
  31.        Usage for information on how to tell man2html the page size and
  32.        margin width/heights of the formatted nroff. Depagination can be
  33.        turned off with the -nodepage command-line option.
  34.        
  35.      * Creates links to other manpages if the -cgiurl command-line option
  36.        is specified.
  37.        
  38.    By default, man2html does not put a title, <TITLE>, in the HTML file.
  39.    However, one can specify a title via the -title command-line option.
  40.    
  41.    man2html also has support for processing output generated from manpage
  42.    keyword search, "man -k". See Keyword Search for more information.
  43.    
  44.  
  45.    
  46.      _________________________________________________________________
  47.    
  48. Usage
  49.  
  50.    man2html is invoked from a Unix shell, with the following syntax:
  51.    
  52.    % man2html [options] < infile > out.html
  53.    % man unix_command | man2html [options] > out.html
  54.    
  55.    The following options are available:
  56.    
  57.    -bare
  58.           This option will keep man2html from inserting the HTML, HEAD,
  59.           BODY tags from the output. This is useful if you want to
  60.           incorporate the output from man2html into an HTML document.
  61.           
  62.    -botm #
  63.           Use # to be the number of lines representing the bottom margin
  64.           of the formatted nroff input. The lines include any running
  65.           footers. The default value is 7.
  66.           
  67.    -cgiurl string
  68.           Use string as the template URL for linking to other manpages.
  69.           See Linking to Other Manpages for more information on this
  70.           option.
  71.           
  72.    -headmap file
  73.           Read file to determine which HTML header tags are used for
  74.           various section heading in the manpage. See Section Head Map
  75.           File for information on the format of the map file.
  76.           
  77.    -help
  78.           Print out a short usage message of man2html. No other action is
  79.           taken.
  80.           
  81.    -k
  82.           Process input as the results from a manpage keyword search. See
  83.           Keyword Search for more information.
  84.           
  85.    -leftm #
  86.           Use # to be the character width of the left margin of the
  87.           formatted nroff input. The default value is 0.
  88.           
  89.    -nodepage
  90.           Do not merge the manpage into one page. This will cause running
  91.           headers/footers in the formatted nroff to carry over into the
  92.           HTML output.
  93.           
  94.    -noheads
  95.           Do not wrap manpage section heads in HTML header tags.
  96.           
  97.    -pgsize #
  98.           Use # as the page size of the formatted nroff input. The
  99.           default value is 66.
  100.           
  101.    -seealso
  102.           Only create links to other manpages in the SEE ALSO section.
  103.           The option is only valid if the -cgiurl option is specified.
  104.           
  105.    -sun
  106.           Do not require a section head to have bold overstriking in the
  107.           formatted nroff input. The option is called -sun because it was
  108.           on a Sun workstation that section heads in manpages were not
  109.           overstriked.
  110.           
  111.    -title string
  112.           Set the title of the HTML output to string.
  113.           
  114.    -topm #
  115.           Use # to be the number of lines representing the top margin of
  116.           the formatted nroff input. The lines include any running
  117.           footers. The default value is 7.
  118.           
  119.    
  120.    
  121.    
  122.      _________________________________________________________________
  123.    
  124. Section Head Map File
  125.  
  126.    man2html allows you to customize what HTML header tags, <H1> ... <H6>,
  127.    are used in manpage section headings (via the -headmap option).
  128.    Normally, man2html treats lines that are flush to the left margin
  129.    (-leftm), and contain overstriking (overstrike check is canceled
  130.    with the -sun option), as section heads. However, you can
  131.    augment/override what HTML header tags are used for any given section
  132.    head.
  133.    
  134.    In order to write a section head map file, you will need to know about
  135.    Perl associative arrays. You do not need to be an expert in Perl to
  136.    write a map file. However, having knowledge of Perl allows you to be
  137.    more clever when writing a map file.
  138.    
  139.  
  140.   AUGMENTING THE DEFAULT MAP
  141.   
  142.    To add to the default mapping defined by man2html, your map file will
  143.    contain lines with the following syntax
  144.    
  145.    $SectionHead{'<section head text>'} = '<html header tag>';
  146.  
  147.    where,
  148.    
  149.    <section head text>
  150.           Is the text of the manpage section head. Example: `SYNOPSIS'.
  151.           
  152.    <html header tag>
  153.           Is the HTML header tag to wrap the section head in. Legal
  154.           values are: `<H1>', `<H2>', `<H3>', `<H4>', `<H5>', `<H6>'.
  155.           
  156.  
  157.   OVERRIDING THE DEFAULT MAP
  158.   
  159.    To override the default mapping with your own, then your map file will
  160.    have the following syntax:
  161.    
  162.          %SectionHead = (
  163.                    '<section head text>', '<html header tag>',
  164.                    '<section head text>', '<html header tag>',
  165.                    # ... More section head/tag pairs
  166.                    '<section head text>', '<html header tag>',
  167.          );
  168.  
  169.   THE DEFAULT MAP
  170.   
  171.    As of this writing, this is the default map used by man2html:
  172.    
  173.          %SectionHead = (
  174.                    '\S.*OPTIONS.*', '<H2>',
  175.                    'AUTHORS?', '<H2>',
  176.                    'BUGS', '<H2>',
  177.                    'COMPATIBILITY', '<H2>',
  178.                    'DEPENDENCIES', '<H2>',
  179.                    'DESCRIPTION', '<H2>',
  180.                    'DIAGNOSTICS', '<H2>',
  181.                    'ENVIRONMENT', '<H2>',
  182.                    'ERRORS', '<H2>',
  183.                    'EXAMPLES', '<H2>',
  184.                    'EXTERNAL INFLUENCES', '<H2>',
  185.                    'FILES', '<H2>',
  186.                    'LIMITATIONS', '<H2>',
  187.                    'NAME', '<H2>',
  188.                    'NOTES?', '<H2>',
  189.                    'OPTIONS', '<H2>',
  190.                    'REFERENCES', '<H2>',
  191.                    'RETURN VALUE', '<H2>',
  192.                    'SECTION.*:', '<H2>',
  193.                    'SEE ALSO', '<H2>',
  194.                    'STANDARDS CONFORMANCE', '<H2>',
  195.                    'STYLE CONVENTION', '<H2>',
  196.                    'SYNOPSIS', '<H2>',
  197.                    'SYNTAX', '<H2>',
  198.                    'WARNINGS', '<H2>',
  199.                    '\s+Section.*:', '<H3>',
  200.          );
  201.          $HeadFallback = '<H2>';  # Fallback tag if above is not found.
  202.  
  203.    Check the Perl source code of man2html for the latest default mapping.
  204.    
  205.    
  206.    You can reassign the $HeadFallback variable to a different value if
  207.    you choose. This value is used as the header tag of a section head if
  208.    no matches are found in the SectionHead map.
  209.    
  210.  
  211.   USING REGULAR EXPRESSIONS IN THE MAP FILE
  212.   
  213.    You may have noticed unusual characters in the default map file, like
  214.    "\s" or "*". man2html actual treats the <section head text> as a Perl
  215.    regular expression. If you are comfortable with Perl regular
  216.    expressions, then you have the full power of them to use in your map
  217.    file.
  218.    
  219.    Caution:
  220.           man2html already anchors the regular expression to the
  221.           beginning of the line with left margin spacing specified by the
  222.           -leftm option. Therefore, do not use the `^' character to
  223.           anchor your regular expression to the beginning. However, you
  224.           may end your expression with a `$' to anchor it to the end of
  225.           the line.
  226.           
  227.    Since the <section head text> is actually a regular expression, you'll
  228.    have to be careful of special characters if you want them to be
  229.    treated literally. The following characters should be escaped by
  230.    prefixing them by the `\' character if you want Perl to treat the
  231.    character "as is": [ ] ( ) . ^ { } $ * ? + \ |
  232.    
  233.    Caution:
  234.           One should use single quotes to delimit <section head text>
  235.           instead of double quotes. This will preserve any `\' characters
  236.           for character escaping or when the `\' is used for special Perl
  237.           character matching sequences (eg. \s \w \S ).
  238.           
  239.  
  240.   OTHER TID BITS ON THE MAP FILE
  241.   
  242.    Comments can be inserted in the map file by using the '#' character.
  243.    Anything after, and including, the '#' character is ignored, up to the
  244.    end of line.
  245.    
  246.    You might be thinking that the above is quite-a-bit-of-stuff just for
  247.    doing manpage section heads. However, you'll be surprised how much
  248.    better the HTML output looks with header tags, even though, everything
  249.    else is in a <PRE> tag.
  250.    
  251.  
  252.    
  253.      _________________________________________________________________
  254.    
  255. Linking to Other Manpages
  256.  
  257.    man2html allows the ability to link to other manpages referenced. If
  258.    the -cgiurl option is specified, man2html will create anchors that
  259.    link to other manpages.
  260.    
  261.    The URL entered with the -cgiurl option is actually a template that
  262.    determines the actual URL used to link to other manpages. The
  263.    following variables are defined during run time that may be used in
  264.    the template string:
  265.    
  266.      * $title : The title of the manual page referenced.
  267.      * $section: The section number of the manual page referenced.
  268.      * $subsection: The subsection of the manual page referenced.
  269.        
  270.    Any other text in the template is preserved "as is".
  271.    
  272.    Caution:
  273.           man2html evaluates the template string as a Perl expression.
  274.           Therefore, one might need to surround the variable names with
  275.           '{}' (eg. ${title}) so man2html properly recognizes the
  276.           variable.
  277.           
  278.    Note:
  279.           If a CGI program calling man2html is actuall a shell script or
  280.           a Perl program, make sure to properly escape the '$' character
  281.           in the URL template to avoid variable interpolation by the CGI
  282.           program.
  283.           
  284.    Normally, the URL calls a CGI program (hence the option name), but the
  285.    URL can easily link to statically converted documents.
  286.    
  287.   EXAMPLE1
  288.   
  289.    The following template string is specified to call a CGI program to
  290.    retrieve the appropriate manpage linked to:
  291.    
  292.    man.cgi?$section$subsection+$title
  293.    
  294.    If the ls(1) manpage is referenced in the 'SEE ALSO' section, the
  295.    above template will translate to the following URL:
  296.    
  297.    man.cgi?1+ls
  298.    
  299.    The actual HTML markup will look like the following:
  300.    
  301.    <A HREF="man.cgi?1+ls">ls(1)</A>
  302.    
  303.   EXAMPLE2
  304.   
  305.    The following template string is specified to retrieve pre-converted
  306.    manpages:
  307.    
  308.    http://foo.org/man$section/$title.$section$subsection.html
  309.    
  310.    If the mount(1M) manpage is referenced, the above template will
  311.    translate to the following URL:
  312.    
  313.    http://foo.org/man1/mount.1M.html
  314.    
  315.    The actual HTML markup will look like the following:
  316.    
  317.    <A HREF="http://foo.org/man1/mount.1M.html">mount(1M)</A>
  318.    
  319.  
  320.    
  321.      _________________________________________________________________
  322.    
  323. Keyword Search
  324.  
  325.    man2html has the ability to process output generated from "man -k", or
  326.    a keyword search. The options -k and -cgiurl must be specified inorder
  327.    for man2html to parse the input as a keyword search. man2html will
  328.    generate an HTML document of the keyword search with the following
  329.    format:
  330.    
  331.      * All manpage references are listed by section.
  332.        
  333.      * Within each section listing, the manpage references are sorted
  334.        alphabetically (case-sensitive) in a <DL>. The manpage references
  335.        are listed in the <DT> section, and the summary text is listed in
  336.        the <DD> section.
  337.        
  338.      * Each manpage reference listed is a hyperlink to the actual manpage
  339.        as specified by the -cgiurl option.
  340.        
  341.    This ability to process keyword searches gives nice added
  342.    functionality to a WWW forms interface to man(1). Even if you have
  343.    statically converted manpages to HTML via another man->HTML program,
  344.    you can use man2html, and "man -k", to provide keyword search
  345.    capabilites easily for your HTML manpages.
  346.    
  347.    
  348.      _________________________________________________________________
  349.    
  350. Notes
  351.  
  352.      * Different systems format manpages differently. Here is a list of
  353.        recommended command-line options for a given system:
  354.        
  355.           + Convex: <defaults should be okay>
  356.           + HP: -leftm 1 -topm 8
  357.           + Sun: -sun
  358.             
  359.      * Some line spacing gets lost in the formatted nroff since the
  360.        spacing would occur in the middle of a page break. This can cause
  361.        text to be merged that shouldn't be merged when man2html
  362.        depaginates the text. To avoid this problem man2html keeps track
  363.        of the margin indent right before, and after, a page break. If the
  364.        margin width of the line after the page break is less than the
  365.        line before the page break, man2html inserts a blank line in the
  366.        HTML output.
  367.        
  368.      * A manpage cross-reference is detected by the following pseudo
  369.        expression:
  370.        
  371.        [A-z.-+_]+([0-9][A-z]?)
  372.        
  373.      * man2html only recognizes lines with " - " (the normal separator
  374.        between manpage references and summary text) while in keyword
  375.        search mode.
  376.        
  377.      * man2html can be hooked in a CGI script/program to convert manpages
  378.        on the fly. This is the reason for the -cgiurl option.
  379.        
  380.  
  381.    
  382.      _________________________________________________________________
  383.    
  384. Limitations
  385.  
  386.      * The order that section head mapping is searched is not defined.
  387.        Therefore, if two, or more, <section head text> can match a give
  388.        manpage section, there is no way to determine which map tag is
  389.        chosen.
  390.        
  391.  
  392.    
  393.      _________________________________________________________________
  394.    
  395. Bugs
  396.  
  397.      * Text that is flush to the left margin, but is not actually a
  398.        section head, can be mistaken for a section head. This mistake is
  399.        more likely when the -sun option is in affect.
  400.        
  401.  
  402.    
  403.      _________________________________________________________________
  404.    
  405.     Earl Hood, ehood@convex.com
  406.     man2html 2.0.2
  407.